docs(engine): document required server:engine channel allowlist flag#28
Open
AmberCXX wants to merge 1 commit into
Open
docs(engine): document required server:engine channel allowlist flag#28AmberCXX wants to merge 1 commit into
server:engine channel allowlist flag#28AmberCXX wants to merge 1 commit into
Conversation
Channels are research preview — even when the engine MCP server connects fine (`claude mcp list` shows ✓), notifications are silently dropped unless the launching `claude` invocation includes `--dangerously-load-development-channels server:engine`. Without this flag the scheduler fires on time and writes the trigger log, but nothing reaches the agent — so the symptom is "engine never delivers messages" with zero error output, easy to mistake for a deeper bug. - Spell out the flag requirement as a dedicated step in 快速开始 - Show the multi-channel form (`server:hub server:engine`, space-separated) - Add a verification recipe using engine_add_task so users can confirm the channel notification path is actually wired up - Cross-link the Anthropic Channels Reference + forge-launcher (which handles this automatically) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
LinekForge
reviewed
May 13, 2026
Owner
LinekForge
left a comment
LinekForge
left a comment
There was a problem hiding this comment.
感谢这个 PR！填了一个很实际的坑——channel notification 被静默丢弃这个行为确实很容易误判为"engine 不工作"。
整体内容准确，几个小建议：
1. claude mcp add 命令缺少 -- 分隔符
当前：
claude mcp add --scope user engine /Users/<you>/.bun/bin/bun /absolute/path/to/forge-engine/engine-channel.ts官方文档要求 options 在 name 前，name 和 command 之间用 -- 分隔（参考 https://code.claude.com/docs/en/mcp ）。建议改为：
claude mcp add --transport stdio --scope user engine -- /Users/<you>/.bun/bin/bun /absolute/path/to/forge-engine/engine-channel.ts2. 验证 recipe 的代码块风格
当前的 bash 代码块全是注释（# ...），没有可执行命令。README 里其他代码块都是可以直接复制执行的。建议改成一句普通文字说明，比如：
验证方法：在 Claude Code 窗口里让 agent 调用
engine_add_task（设delay_seconds: 30）。30 秒后收到<channel source="engine" ...>消息说明白名单生效；收不到就检查是否漏了server:engine。
这样和文档整体风格更一致。
3. 其他
- [!IMPORTANT] callout 用得恰当
- step 编号正确（4→5）
- 链接都验证过了，没问题
- 多 channel 的空格分隔写法
server:hub server:engine也确认正确（hub-app/WebViewBridge.swift 里已有同样写法）
改完这两处就可以合了。
— Forge
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
claude --dangerously-load-development-channels server:engineis required for engine notifications to be delivered. Without it, the MCP subprocess connects fine and the scheduler fires on time, but every notification is silently dropped — easy to mistake for "engine doesn't work" when the root cause is a missing launch flag.server:hub server:engine(space-separated, not comma).engine_add_taskwith a 30-second delay so users can confirm the channel notification path end-to-end.Motivation
Real debug session that triggered this: ~1 week of "engine sometimes works, sometimes doesn't" symptoms turned out to be a single missing
server:enginetoken in the launchingclaudecommand.claude mcp listshowed✓ Connectedthe whole time, which strongly suggested the engine MCP was fine — but the trigger log was the only evidence anything fired, because notifications were dropped by Claude Code's research-preview allowlist. The README didn't mention this flag at all, so users following it would hit the same wall.Scope
Docs-only — touches
forge-engine/README.mdonly.Test plan
git -c core.quotepath=false status --short --untracked-files=all→ onlyforge-engine/README.mdmodifiedgrep -rE '@im\.wechat|ou_[a-f0-9]{16,}|sk-ant-[a-zA-Z0-9_-]{20,}|sk-[a-zA-Z0-9_-]{20,}|[0-9]{9,10}:[A-Za-z0-9_-]{35}'→ no hits in changed fileclaude mcp add --scope user,--dangerously-load-development-channels server:<name>,engine_add_taskall real)🤖 Generated with Claude Code